home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 20 / Cream of the Crop 20 (Terry Blount) (1996).iso / os2 / xdsn217.zip / DOC / os2api.txt < prev    next >
Text File  |  1996-07-10  |  3KB  |  105 lines
  1. OS2API.TXT                          Copyright (c) 1996 xTech Ltd
  2. ----------------------------------------------------------------
  3.  
  4.                  Native XDS-x86 OS/2 Edition
  5.                  ---------------------------
  6.                      v2.17 (pre-release)
  7.  
  8.                       OS/2 API support
  9.  
  10.  
  11. 1. Introduction
  12. ---------------
  13.  
  14. This file contains the short description of XDS OS/2 API support
  15. usage in your Modula-2/Oberon-2 programs. This feature is not
  16. covered in the documentation yet, but it already exists in the
  17. pre-release version and we'd like it to be tested.
  18.  
  19.  
  20. 2. Requirements
  21. ---------------
  22.  
  23. This distribution does not yet include the OS/2 API libraries, which
  24. you should have in order to access the API from your programs.
  25. These libraries are the part of the IBM Developer's Toolkit for OS/2,
  26. which is available on the Developers Connection CD-ROMs and along with
  27. some C compilers, for instance, IBM VisualAge C++ or Watcom.
  28.  
  29. We've asked IBM for permission to incorporate these libraries into
  30. XDS package, but have no answer yet.
  31.  
  32.  
  33. 3. OS/2 API definition module - OS2.DEF
  34. ---------------------------------------
  35.  
  36. The whole API is defined in a single Modula-2 definition module OS2.DEF,
  37. which resides in the DEF subdirectory of the distribution. It is very
  38. large (more than 1Mb) and its symbolic file would be very large too
  39. and would create the big time and memory overhead during compilation.
  40. Fortunately, the original C header files were built using conditional
  41. compilaion sections - you have to define a constant (like INCL_DOSPROCESS)
  42. before including the main OS2.H header file to select the appropriate
  43. section. This idea, as well as constant names, is preserved in XDS.
  44.  
  45. Thus, to use an OS/2 API call in your program:
  46.  
  47. A. Declare the correspondent INCL_xxx option in the PROJECT file. 
  48.    For example:
  49.  
  50. -INCL_DOSPROCESS:+
  51.  
  52. B. Depending on whether your program is a text-mode or a Presentation
  53.    Manager application, toggle the VIO or PM option ON in the PROJECT 
  54.    file:
  55.  
  56. +PM
  57.  
  58. C. Add the module OS2 to the import list of your program. You can use
  59.    qualified or unqualified import:
  60.  
  61. IMPORT OS2;                 (* qualified *)
  62.  
  63. FROM OS2 IMPORT DosBeep;    (* unqualified *)
  64.  
  65. D. Now you can insert the required call:
  66.  
  67. OS2.DosBeep(1000,100);      (* qualified *)
  68.  
  69. DosBeep(1000,100);          (* unqualified *)
  70.  
  71. NOTE 1:
  72.  
  73.    If you have to pass a procedure as a parameter to the API call (a window
  74.    procedure, for example), you should specify the "SysCall" calling
  75.    convention:
  76.  
  77.    PROCEDURE ["SysCall"] MyWindowProc
  78.    ( hwnd         : HWND;
  79.      msg          : LONGCARD;
  80.      mp1          : MPARAM;
  81.      mp2          : MPARAM
  82.    )              : MRESULT;
  83.  
  84. NOTE 2:
  85.  
  86.    If your application uses resources, you'll have to incorporate the
  87.    binary resource file into the executable by hand. You may use the
  88.    OS/2 resource compiler (RC.EXE):
  89.  
  90.    rc myapp.res myapp.exe
  91.  
  92.    This inconvenient approach will be changed in future releases.
  93.  
  94. NOTE 3:
  95.  
  96.    You have to manually force recompilation of OS2.DEF file after you add or
  97.    remove INCL_xxx options from your project. To achieve this, either
  98.    remove the OS2.SYM file or use the =all submode when making your project.
  99.  
  100. See also the Modula-2 sample PM application in SAMPLES\MAND subdirectory.
  101.  
  102.  
  103.  
  104.                         [end of document]
  105.